docs(concepts): improve writing style #3354
Conversation
bandantonio
requested review from
quetzalliwrites and
asyncapi-bot-eve
as code owners
WalkthroughThe changes across multiple markdown documents focus on enhancing clarity, consistency, and readability of the content related to AsyncAPI concepts. Key terms are emphasized, sentence structures are refined, and descriptions are streamlined to improve the overall flow of information. Specific adjustments include rephrasing definitions, clarifying roles and relationships within Event-Driven Architecture, and ensuring consistent terminology throughout the documents. Diagrams and their descriptions have also been updated for better comprehension. Changes
Suggested labels
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
✅ Deploy Preview for asyncapi-website ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
asyncapi-bot
requested review from
BhaswatiRoy,
J0SAL,
TRohit20 and
VaishnaviNandakumar
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #3354 +/- ##
=======================================
Coverage 49.14% 49.14%
=======================================
Files 21 21
Lines 647 647
=======================================
Hits 318 318
Misses 329 329 ☔ View full report in Codecov by Sentry. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Outside diff range and nitpick comments (11)
markdown/docs/concepts/channel.md (1)
10-10: Consider refining the sentence structure for better flow.While the content is accurate and clear, the flow could be improved slightly.
Consider this revision:
-Channels are pivotal for establishing communication between producers and consumers. They enable producers to send messages, while consumers receive messages from specific channels. The primary function of a channel is to ensure that the intended messages reach the appropriate consumers. +Channels play a pivotal role in establishing communication between producers and consumers. They enable producers to send messages and consumers to receive messages from specific channels. Their primary function is to ensure that messages reach their intended consumers.markdown/docs/concepts/application.md (1)
8-10: Update spelling of "micro-service" to "microservice".The definition changes improve clarity and readability. However, the term "micro-service" should be "microservice" as per common industry usage.
-An application can be a micro-service, IoT (Internet of things) device (for example, a sensor), mainframe process, and more. +An application can be a microservice, IoT (Internet of things) device (for example, a sensor), mainframe process, and more.🧰 Tools
🪛 LanguageTool
[misspelling] ~10-~10: This word is normally spelled as one.
Context: ...roup of them. An application can be a micro-service, IoT (Internet of things) device (for e...(EN_COMPOUNDS_MICRO_SERVICE)
markdown/docs/concepts/message.md (2)
7-7: LGTM! Consider standardizing technical term formatting.The definition and explanation are clear and technically accurate. The use of italics for message and metadata is good, but consider using consistent formatting for other technical terms like "JSON", "XML", "headers", and "properties" - either as inline code blocks or italics.
Also applies to: 9-9
Line range hint
24-35: LGTM! Consider adding brief descriptions for Query and Command.The comparison between messages and events is well-structured and clear. The diagram effectively shows the hierarchy. However, while events are defined, the concepts of Query and Command are introduced in the diagram but not explained in the text.
Consider adding brief descriptions for Query and Command to maintain consistency with how Events are explained.
markdown/docs/concepts/consumer.md (1)
12-12: Consider clarifying what "completing the event data flow" means.While the addition emphasizes the consumer's importance, it might be helpful to explicitly state what "completing the event data flow" entails, such as processing, transforming, or storing the event data.
Consider this revision:
-When you want your application to process events asynchronously, the consumer plays a crucial role in completing the event data flow through the event channel. +When you want your application to process events asynchronously, the consumer plays a crucial role by receiving and processing events from the event channel, completing the event data flow.markdown/docs/concepts/asyncapi-document/index.md (2)
Line range hint
10-39: Consider adding inline comments to enhance example readability.While the YAML example is well-structured, adding strategic comments would help readers understand the purpose of each section better.
asyncapi: 3.0.0 info: title: Cool Example version: 0.1.0 + # Define the channels where messages can be exchanged channels: userSignedUp: address: user/signedup + # Define the structure of messages that can be sent messages: userSignedUp: description: An event describing that a user just signed up. payload: type: object properties: fullName: type: string email: type: string format: email age: type: integer minimum: 18 +# Define the operations (actions) that can be performed operations: userSignedUp: action: send channel: $ref: '#/channels/userSignedUp'
40-40: Consider adding protocol-specific field examples.The note about protocol-specific fields could be more helpful with concrete examples.
Consider expanding with examples like:
Depending on the implemented protocol (such as MQTT, AMQP, Kafka, etc.), you may have additional fields in your AsyncAPI document. For example, for <a href= "https://github.com/asyncapi/bindings/tree/master/kafka">configuring Kafka bindings</a>. + +Examples of protocol-specific fields: +- MQTT: QoS level, retain flag +- Kafka: partition key, consumer group +- AMQP: routing key, exchange typemarkdown/docs/concepts/producer.md (1)
Line range hint
7-36: Consider adding a summary sectionThe document flows well, but could benefit from a brief summary section at the end that ties together the key points about producers. This would reinforce the main concepts and provide a quick reference for readers.
Example addition:
## Summary A producer is a fundamental component in event-driven architecture that: - Detects and publishes events as messages - Acts as the first layer in the publish/subscribe model - Can potentially serve as both publisher and subscriber🧰 Tools
🪛 LanguageTool
[grammar] ~16-~16: Did you mean the noun “publishing”?
Context: ...or. ## Why do we need Producers? The publish/subscribe communication model is one of...(PREPOSITION_VERB)
markdown/docs/concepts/server.md (3)
8-8: LGTM! Consider standardizing terminology.The definition is technically accurate and provides a clear distinction from traditional API servers. However, the terms "messaging broker" and "message broker" are used interchangeably in this paragraph. Consider standardizing to one form throughout the documentation.
-A _server_ acts as a _messaging broker_ system +A _server_ acts as a _message broker_ system
11-11: Consider clarifying the term "clients".The explanation effectively describes the server's purpose. However, the term "clients" is italicized but not linked or explicitly defined. Consider either linking to a clients concept page (if it exists) or briefly clarifying what constitutes a client in this context.
38-38: Enhance diagram explanation and maintain consistent formatting.While the explanation is technically accurate, consider these improvements:
- The term
brokershould be consistently formatted (either as code or italics)- The explanation could more explicitly connect to the diagram elements
-The diagram above illustrates the Broker-centric Architecture. In this case, there are three AsyncAPI files for the `producer`, `consumer1`, and `consumer2`. In these AsyncAPI files, the [`Server Object`](https://www.asyncapi.com/docs/reference/specification/latest#serverObject) provides information about the `broker`, so that API users know where to connect to start receiving or sending messages. +The diagram above illustrates the Broker-centric Architecture. In this case, there are three AsyncAPI files: one for the `producer` (left), and two for the consumers (`consumer1` and `consumer2`, right). In these AsyncAPI files, the [`Server Object`](https://www.asyncapi.com/docs/reference/specification/latest#serverObject) provides information about the `broker` (middle), enabling API users to establish connections for sending and receiving messages.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (9)
markdown/docs/concepts/application.md(2 hunks)markdown/docs/concepts/asyncapi-document/index.md(2 hunks)markdown/docs/concepts/channel.md(2 hunks)markdown/docs/concepts/consumer.md(2 hunks)markdown/docs/concepts/index.md(1 hunks)markdown/docs/concepts/message.md(3 hunks)markdown/docs/concepts/producer.md(2 hunks)markdown/docs/concepts/protocol.md(3 hunks)markdown/docs/concepts/server.md(3 hunks)
✅ Files skipped from review due to trivial changes (1)
- markdown/docs/concepts/protocol.md
🧰 Additional context used
🪛 LanguageTool
markdown/docs/concepts/application.md
[misspelling] ~10-~10: This word is normally spelled as one.
Context: ...roup of them. An application can be a micro-service, IoT (Internet of things) device (for e...
(EN_COMPOUNDS_MICRO_SERVICE)
markdown/docs/concepts/producer.md
[grammar] ~16-~16: Did you mean the noun “publishing”?
Context: ...or. ## Why do we need Producers? The publish/subscribe communication model is one of...
(PREPOSITION_VERB)
🔇 Additional comments (11)
markdown/docs/concepts/index.md (1)
8-8: Excellent improvements to the documentation structure!
The changes effectively improve readability by:
- Simplifying the header while moving the descriptive text to the introduction
- Using proper emphasis on key terms
- Adopting a more direct and professional tone
These modifications align perfectly with documentation best practices and the PR's objective of improving writing style.
Also applies to: 10-10
markdown/docs/concepts/channel.md (1)
7-7: Well-crafted definition with clear terminology!
The definition effectively explains the concept while maintaining consistency in formatting (italicized key terms) and providing valuable context about protocol-specific variations.
markdown/docs/concepts/application.md (2)
13-13: LGTM! Clear explanation of application roles.
The rephrasing improves clarity while maintaining technical accuracy. The added condition about protocol adherence provides valuable context for readers.
23-24: LGTM! Improved diagram description.
The new description better aligns with the mermaid diagram and provides a clearer explanation of the message flow between applications.
markdown/docs/concepts/consumer.md (3)
7-7: LGTM! Improved terminology precision.
The change from "listens for" to "subscribes to" better reflects the standard terminology in Event-Driven Architecture.
10-10: LGTM! Enhanced explanation of EDA principles.
The revised explanation better clarifies both the asynchronous nature and the decoupled characteristics of consumers in Event-Driven Architecture.
29-30: LGTM! Improved diagram description.
The revised description provides a clearer and more structured explanation of the event flow, making it easier for readers to understand the relationship between producers, brokers, and consumers.
markdown/docs/concepts/asyncapi-document/index.md (1)
6-6: Writing improvements enhance clarity and readability!
The revised text effectively:
- Uses active voice for better engagement
- Maintains technical accuracy while improving flow
- Clearly explains the document's role in API description and message communication
Also applies to: 8-8
markdown/docs/concepts/producer.md (3)
7-13: Well-crafted improvements to the definition and examples!
The changes enhance readability through:
- Appropriate emphasis on key terms using italics
- More precise verb choices ("detects" instead of "senses")
- Clearer, more consistent examples
16-16: Clear and accurate explanation of the publish/subscribe model!
The restructured sentence effectively emphasizes the importance of the publish/subscribe model in event-driven architecture.
🧰 Tools
🪛 LanguageTool
[grammar] ~16-~16: Did you mean the noun “publishing”?
Context: ...or. ## Why do we need Producers? The publish/subscribe communication model is one of...
(PREPOSITION_VERB)
Line range hint 24-36: Excellent improvements to diagram descriptions!
The updated descriptions:
- Better align with the visual representations
- Clearly explain the dual role capability (producer/consumer)
- Provide a smoother reading experience
🧰 Tools
🪛 LanguageTool
[grammar] ~16-~16: Did you mean the noun “publishing”?
Context: ...or. ## Why do we need Producers? The publish/subscribe communication model is one of...
(PREPOSITION_VERB)
markdown/docs/concepts/channel.md
Outdated
|
|
||
| The diagram above illustrates the communication process between a producer and a consumer. The producer sends a message through the channel, which then queues the message for delivery to the specific consumer. |
There was a problem hiding this comment.
Update description to match the diagram's multiple consumers.
The current description mentions "specific consumer" in singular form, but the diagram shows multiple consumers receiving messages from the channel.
Consider this revision:
-The diagram above illustrates the communication process between a producer and a consumer. The producer sends a message through the channel, which then queues the message for delivery to the specific consumer.
+The diagram above illustrates the communication process between a producer and multiple consumers. The producer sends a message through the channel, which then queues the message for delivery to the connected consumers.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The diagram above illustrates the communication process between a producer and a consumer. The producer sends a message through the channel, which then queues the message for delivery to the specific consumer. | |
| The diagram above illustrates the communication process between a producer and multiple consumers. The producer sends a message through the channel, which then queues the message for delivery to the connected consumers. |
markdown/docs/concepts/message.md
Outdated
| @@ -17,11 +18,10 @@ A{{sender application}} --> b --> C{{receiver application}} | |||
|
|
|||
| ``` | |||
|
|
|||
| In the diagram above, the sender application transmits a `message` to the receiver application. | |||
| The diagram above illustrates the sender application that transmits a message to the receiver application. | |||
There was a problem hiding this comment.
🛠️ Refactor suggestion
Enhance the diagram description for better context.
While accurate, the description could be more informative by explaining the channel's role and connecting it to the previous definition.
Consider this enhancement:
- The diagram above illustrates the sender application that transmits a message to the receiver application.
+ The diagram above illustrates how a sender application transmits a message through a channel to a receiver application, demonstrating the basic flow of message-based communication.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| The diagram above illustrates the sender application that transmits a message to the receiver application. | |
| The diagram above illustrates how a sender application transmits a message through a channel to a receiver application, demonstrating the basic flow of message-based communication. |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-3354--asyncapi-website.netlify.app/ |
|
@bandantonio Are these changes made in consideration with @quetzalliwrites? I don't find any concerned issue linked with this PR. |
|
@akshatnema Sure, this was discussed with @quetzalliwrites some time ago. I pinged her again, so we could probably create an 'epic' issue for that so I can take care of all the related styling aspects across the docs. |
|
Hola @akshatnema, thanks for looping me in! 😸 Yes, the good news it that Anthony had already talked to me about his suggestions offline. (I still need to review this PR and see if I agree tehehe) Ah, @bandantonio, to Akshat's point, would you mind creating a new docs issue for your proposal to link to this PR? He makes a good point that a change proposed like this one needs a docs issue. |
There was a problem hiding this comment.
Wow, these changes are FANTASTIC, truly valuable work @bandantonio!!!
Thank you for making these improvements, and I agree the style guide would benefit from incorporating a guideline about italicizing the first time a NEW term is introduced.
That said, we should explicitely add this new rule to our current EPIC issue for the Style Guide: #1240.
I know, I know, we haven't merged the Style Guide yet?! Whattt? 😸
Description
This PR improves writing style of the documents located in the Concepts section.
Motivation: make writing more consistent and predictable, as well as easier to skim and understand.
Fixes #3374
Summary by CodeRabbit